What is @octokit/oauth-authorization-url?
@octokit/oauth-authorization-url is a package that helps you generate OAuth authorization URLs for GitHub. This is useful for applications that need to authenticate users via GitHub and obtain an OAuth token for accessing GitHub APIs on behalf of the user.
What are @octokit/oauth-authorization-url's main functionalities?
Generate OAuth Authorization URL
This feature allows you to generate an OAuth authorization URL that you can redirect users to. The URL includes the necessary query parameters such as client ID, scopes, and state.
const { OAuthApp } = require('@octokit/oauth-authorization-url');
const app = new OAuthApp({
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
});
const url = app.getAuthorizationUrl({
scopes: ['repo', 'user'],
state: 'random-string'
});
console.log(url);
Other packages similar to @octokit/oauth-authorization-url
passport-github
passport-github is a Passport strategy for authenticating with GitHub using the OAuth 2.0 API. It is more comprehensive as it integrates with the Passport.js authentication middleware, providing a complete solution for GitHub authentication.
simple-oauth2
simple-oauth2 is a library that provides a simple and consistent way to handle OAuth 2.0 authorization flows. It is more generic and can be used with various OAuth 2.0 providers, not just GitHub.
node-oauth2-server
node-oauth2-server is a complete, framework-agnostic module for implementing OAuth 2.0 servers. It is more complex and provides a full-fledged OAuth 2.0 server implementation, which is useful if you need to manage OAuth tokens and authorization flows on your own server.
oauth-authorization-url.js
Universal library to retrieve GitHub’s identity URL for the OAuth web flow
![Build Status](https://github.com/octokit/oauth-authorization-url.js/workflows/Test/badge.svg)
See GitHub’s Developer Guide for the OAuth App web application flow. Note that the OAuth web application flow for GitHub Apps is slightly different. GitHub Apps do not support scopes for its user access tokens (they are called user-to-server tokens for GitHub Apps), instead they inherit the user permissions from the GitHub App's registration and the repository/organization access and permissions from the respective installation.
Usage
Browsers
|
Load @octokit/oauth-authorization-url directly from cdn.skypack.dev
<script type="module">
import { oauthAuthorizationUrl } from "https://cdn.skypack.dev/@octokit/oauth-authorization-url";
</script>
|
---|
Node
|
Install with npm install @octokit/oauth-authorization-url
const { oauthAuthorizationUrl } = require("@octokit/oauth-authorization-url");
|
---|
For OAuth Apps
const {
url,
clientId,
redirectUrl,
login,
scopes,
state,
} = oauthAuthorizationUrl({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
redirectUrl: "https://example.com",
login: "octocat",
scopes: ["repo", "admin:org"],
state: "secret123",
});
For GitHub Apps
const { url, clientId, redirectUrl, login, state } = oauthAuthorizationUrl({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
redirectUrl: "https://example.com",
login: "octocat",
state: "secret123",
});
Options
name
|
description
|
---|
clientId
|
Required. The client ID you received from GitHub when you registered.
|
---|
clientType
|
Must be set to either "oauth-app" or "github-app" . Defaults to "oauth-app" .
|
---|
redirectUrl
|
The URL in your application where users will be sent after authorization. See Redirect URLs in GitHub’s Developer Guide.
|
---|
login
|
Suggests a specific account to use for signing in and authorizing the app.
|
---|
scopes
|
Only relevant when clientType is set to "oauth-app" .
An array of scope names (or: space-delimited list of scopes). If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
Defaults to [] if clientType is set to "oauth-app" .
|
---|
state
|
An unguessable random string. It is used to protect against cross-site request forgery attacks.
Defaults to Math.random().toString(36).substr(2) .
|
---|
allowSignup
|
Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. Use false in the case that a policy prohibits signups. Defaults to true .
|
---|
baseUrl
|
When using GitHub Enterprise Server, set the baseUrl to the origin, e.g. https://github.my-enterprise.com .
|
---|
Result
oauthAuthorizationUrl()
returns an object with the following properties
name
|
description
|
---|
allowSignup
|
Returns options.allowSignup if it was set. Defaults to true .
|
---|
clientType
|
Returns options.clientType . Defaults to "oauth-app" .
|
---|
clientId
|
Returns options.clientId .
|
---|
login
|
Returns options.login if it was set. Defaults to null .
|
---|
redirectUrl
|
Returns options.redirectUrl if it was set. Defaults to null .
|
---|
scopes
|
Only set if options.clientType is set to "oauth-app" .
Returns an array of strings. Returns options.scopes if it was set and turns the string into an array if a string was passed, otherwise [] .
|
---|
state
|
Returns options.state if it was set. Defaults to Defaults to Math.random().toString(36).substr(2) .
|
---|
url
|
The authorization URL
|
---|
Types
import {
ClientType,
OAuthAppOptions,
OAuthAppResult,
GitHubAppOptions,
GitHubAppResult,
} from "@octokit/oauth-authorization-url";
License
MIT